---
title: Knowledge Contents DB
description: "Learn how to add a Content DB to your Knowledge."
sidebarTitle: Contents DB
keywords: [contents db]
---
The Contents Database (Contents DB) is an optional component that enhances Knowledge with content tracking and management features. It acts as a control layer that maintains detailed records of all content added to your `Knowledge`.

## What is Contents DB?

Contents DB is a table in your database that keeps track of what content you've added to your Knowledge base. 
While your vector database stores the actual content for search, this table tracks what you've added, when you added it, and its processing status.

- **Vector Database**: Stores embeddings and chunks for semantic search
- **Contents Database**: Tracks content metadata, status, and when coupled with [AgentOS Knowledge](/agent-os/features/knowledge-management), provides management of your knowledge via API.

## Why Use ContentsDB?

### Content Visibility and Control
Without ContentsDB, managing your knowledge and vectors is difficult - you can search it, but you can't manage individual pieces of content or alter all the vectors created from a single piece of content.

With ContentsDB, you gain full visibility:
- See all content that has been added
- Track processing status of each item
- View metadata and file information
- Monitor access patterns and usage

### Powerful Management Capabilities
- **Edit names, descriptions and metadata** for existing content
- **Delete specific content** and automatically clean up associated vectors
- **Update content** without rebuilding the entire knowledge base
- **Batch operations** for managing multiple content items
- **Status tracking** to monitor processing success/failure

### Required for AgentOS
If you're using AgentOS, ContentsDB is **mandatory** for the Knowledge page functionality. The AgentOS web interface relies on ContentsDB to display and manage your knowledge content.

## Setting Up ContentsDB

### Choose Your Database

Agno supports multiple database backends for ContentsDB:

- **[PostgreSQL](/concepts/db/postgres)** - Recommended for production
- **[SQLite](/concepts/db/sqlite)** - Great for development and single-user applications  
- **[MySQL](/concepts/db/mysql)** - Enterprise-ready relational database
- **[MongoDB](/concepts/db/mongodb)** - Document-based NoSQL option
- **[Redis](/concepts/db/redis)** - In-memory option for high performance
- **[In-Memory](/concepts/db/in_memory)** - Temporary storage for testing
- **Cloud Options** - [DynamoDB](/concepts/db/dynamodb), [Firestore](/concepts/db/firestore), [GCS](/concepts/db/gcs)

### Basic Setup Example

```python
from agno.knowledge import Knowledge
from agno.db.postgres import PostgresDb
from agno.vectordb.pgvector import PgVector

# Set up ContentsDB - tracks content metadata
contents_db = PostgresDb(
    db_url="postgresql+psycopg://user:pass@localhost:5432/db",
    knowledge_table="knowledge_contents"  # Optional: custom table name
)

# Set up vector database - stores embeddings
vector_db = PgVector(
    table_name="vectors",
    db_url="postgresql+psycopg://user:pass@localhost:5432/db"
)

# Create Knowledge with both databases
knowledge = Knowledge(
    name="My Knowledge Base",
    vector_db=vector_db,
    contents_db=contents_db  # This enables content tracking!
)
```

### Alternative Database Examples

```python
# SQLite for development
from agno.db.sqlite import SqliteDb
contents_db = SqliteDb(db_file="my_knowledge.db")

# MongoDB for document-based storage
from agno.db.mongo import MongoDb
contents_db = MongoDb(
    uri="mongodb://localhost:27017",
    database="agno_db"
)

# In-memory for testing
from agno.db.in_memory import InMemoryDb
contents_db = InMemoryDb()
```

## Core Functionality

### Contents DB Schema

If you have a Contents DB configured for your Knowledge, the content metadata will be stored in a contents table in your database.

The schema for the contents table is as follows:

| Field | Type | Description |
|-------|------|-------------|
| `id` | `str` | The unique identifier for the content. |
| `name` | `str` | The name of the content. |
| `description` | `str` | The description of the content. |
| `metadata` | `dict` | The metadata for the content. |
| `type` | `str` | The type of the content. |
| `size` | `int` | The size of the content. Applicable only to files. |
| `linked_to` | `str` | The ID of the content that this content is linked to. |
| `access_count` | `int` | The number of times this content has been accessed. |
| `status` | `str` | The status of the content. |
| `status_message` | `str` | The message associated with the status of the content. |
| `created_at` | `int` | The timestamp when the content was created. |
| `updated_at` | `int` | The timestamp when the content was last updated. |
| `external_id` | `str` | The external ID of the content. Used when external vector stores are used, like LightRAG. |

This data is best displayed on the [knowledge page of the AgentOS UI](https://os.agno.com/knowledge).

### Content Metadata Tracking

```python
# When you add content
knowledge.add_content(
    name="Product Manual",
    path="docs/manual.pdf",
    metadata={"department": "engineering", "version": "2.1"}
)

# ContentsDB automatically stores all the fields from the schema above
# - External IDs for cloud integrations
```

### Content Retrieval and Management

```python
# Get all content with pagination
contents, total_count = knowledge.get_content(
    limit=20,
    page=1,
    sort_by="created_at",
    sort_order="desc"
)

# Get specific content by ID
content = knowledge.get_content_by_id(content_id)

# Each content object includes:
print(content.name)         # Content name
print(content.description)  # Description
print(content.metadata)     # Custom metadata
print(content.file_type)    # File type (.pdf, .txt, etc.)
print(content.size)         # File size in bytes
print(content.status)       # Processing status
print(content.created_at)   # When it was added
print(content.updated_at)   # Last modification
```

## Management Features

### Content Deletion with Vector Cleanup

Delete content and automatically clean up associated vectors:

This automatically:
1. Removes the content metadata from ContentsDB
2. Deletes associated vectors from the vector database
3. Maintains consistency between both databases

```python
# Delete specific content
knowledge.remove_content_by_id(content_id)

# Delete all content
knowledge.remove_all_content()
```

### Filtering and Search

ContentsDB enables powerful filtering capabilities:

```python
# The knowledge base tracks valid filter keys
valid_filters = knowledge.get_filters()

# Filter content during search
results = knowledge.search(
    query="technical documentation",
    filters={"department": "engineering", "version": "2.1"}
)
```

## AgentOS Integration

### Required Setup for AgentOS

When using AgentOS, ContentsDB is mandatory for the Knowledge management interface:

```python
from agno.os import AgentOS
from agno.db.postgres import PostgresDb
from agno.agent import Agent

# ContentsDB is required for AgentOS Knowledge page
contents_db = PostgresDb(
    db_url="postgresql+psycopg://user:pass@localhost:5432/db"
)

vector_db = PgVector(table_name="vectors", db_url="http://my-postgress:5432")


knowledge = Knowledge(
    vector_db=vector_db,
    contents_db=contents_db  # Must be provided for AgentOS
)

knowledge_agent = Agent(
    name="Knowledge Agent",
    knowledge=knowledge
)

# Create AgentOS app
app = AgentOS(
    description="Example app for basic agent with knowledge capabilities",
    id="knowledge-demo",
    agents=[knowledge_agent],
)
```

### AgentOS Features Enabled by ContentsDB

With ContentsDB, the AgentOS Knowledge page provides:

- **Content Browser**: View all uploaded content with metadata
- **Upload Interface**: Add new content through the web UI
- **Status Monitoring**: Real-time processing status updates
- **Metadata Editor**: Update content metadata through forms
- **Content Management**: Delete or modify content entries
- **Search and Filtering**: Find content by metadata attributes
- **Bulk Operations**: Manage multiple content items at once

Check out the [AgentOS Knowledge](/agent-os/features/knowledge-management) page for more in-depth information.

## Next Steps

<CardGroup cols={2}>
  <Card title="Vector Databases" icon="database" href="/concepts/vectordb/overview">
    Understand the embedding storage layer
  </Card>
  <Card title="AgentOS" icon="server" href="/agent-os/introduction">
    Use your Knowledge in Agno AgentOS
  </Card>
  <Card title="Database Setup" icon="wrench" href="/concepts/db/overview">
    Detailed database configuration guides
  </Card>
  <Card title="Getting Started" icon="rocket" href="/concepts/knowledge/getting-started">
    Build your first knowledge-powered agent
  </Card>
</CardGroup>

